home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / optans10.zip / OPTANSI.DOC < prev    next >
Text File  |  1992-06-14  |  60KB  |  1,295 lines
  1. *******************************************************************************
  2.  
  3.                                OptANSI Library
  4.                                  version 1.0
  5.                          Copyright 1992 Michael Dannov
  6.  
  7.                   Optimizing ANSI Output Library for Borland C
  8.  
  9. *******************************************************************************
  10.                                 DOCUMENTATION
  11. ------------------------------------------------------------------------------
  12. *ABOUT OPTANSI*
  13.  
  14. What is the OptANSI Library?
  15.      OptANSI was designed to output fully optimized and compressed ANSI codes
  16. on the fly to any ANSI interpreting device. It is NOT an interpreter by any
  17. means, so it does not receive incoming ANSI and convert it into logical screen
  18. output. Usually this control is left to the ANSI device or the comm program.
  19.  
  20. Who can use the OptANSI Library?
  21.      Anyone who programs in Borland C and has need to use the ANSI screen
  22. interface can use OptANSI. It is well suited for most communication appli-
  23. cations like BBS programs, remote doorways, fossil drivers, telecommunication
  24. programs, and BBS doors. It can also be used with ANSI drawing packages and
  25. other ANSI utilities. In fact, it has been used to design the popular AOPT
  26. (ANSI Optimizer) utility which takes standard .ANS files and reduces them to
  27. their minimum size without affecting resulting output. You may also find other
  28. uses for OptANSI if you simply want an alternative method for screen output
  29. aside from VIDEO BIOS, direct screen, or DOS calls. All OptANSI functions can
  30. be piped through DOS if you use standard printf() and other DOS forwarding
  31. calls, thereby allowing you to send screen locations and color codes to the
  32. screen or to a file. This is especially useful if standard conio is not always
  33. appropriate or compatible; for instance, DOS shells using telecommunications
  34. without a gateway.
  35.  
  36. Why use the OptANSI Library, say as opposed to another?
  37.      There are a number of generic ANSI libraries out there to use. I might
  38. have used them myself if I hadn't grown so critical of all the wasted time
  39. sending unnecessary codes. ANSI is a slow interface by design and there is
  40. little sense wasting good process time on unneeded output. For instance, say
  41. you are using your 2400 baud modem online with a BBS who's sysop loves
  42. switching between those ANSI colors. It takes a lot of time to draw the screen
  43. at that speed and any sort of optimization at all could be beneficial. OptANSI
  44. will practically never result in slower output even if your application uses
  45. 14400 baud transfers. OptANSI should not impede output times; it can only
  46. benefit them.
  47.      OptANSI functions will produce output that is 10-30% smaller of all
  48. output sent (ie, ANSI and all other text) compared with other libraries. Of
  49. pure ANSI output, OptANSI produces 20-60% smaller output. Both these figures
  50. are dependant on how intensive your the of ANSI.
  51.      Another important feature is that OptANSI has ten times the number of
  52. functions as other libraries. It's true, many of these are macros that call
  53. coded functions, but the underlying code and data (if ALL functions in the
  54. library are used) occupies less than 1.5K of memory.
  55.  
  56. How can I use OptANSI Library?
  57.      First, link the OptANSI LIBrary file to your project. Second, all OptANSI
  58. functions are very similar to conio functions, so it shouldn't be to much of
  59. a strain to learn and use. The function names use a one letter suffix "a" for
  60. ANSI. An example is gotoxy(x, y) which in OptANSI is agotoxy(x, y, &x, &y).
  61. OptANSI functions are very tight. Much of the code is written in assembly
  62. using optimized BC asm inlines. Also, the library is spread out so that only
  63. functions called by your program are actually linked into the executable.
  64.  
  65. How does OptANSI work?
  66.      OptANSI, unlike rival libraries, remembers critical information about its
  67. former states, like last cursor position and previous color. OptANSI takes
  68. advantage of all the ASCII and ANSI rules to take advantage of all possible
  69. shortcuts and will 99.9% of the time find the shortest output path.
  70.  
  71. There seem to be a number of ANSI standards; by which one does OptANSI comply?
  72.      OptANSI is mostly composed of a combination of the shared rules of many
  73. different ANSI devices or at least their expected operations. There have been
  74. bugs in various ANSI drivers released over the last 10 years. ANSI.SYS which
  75. accompanies DOS is no exception. OptANSI has been tested with most public ANSI
  76. drivers and certain flags have been implemented to allow the programmer or the
  77. user (if designed to do so) to decide which outputs are valid to optimize.
  78.      OptANSI also includes a number of functions that the programmer can
  79. decide whether or not to implement. Some of the NANSI (New ANSI) and other
  80. ANSI extensions have been included like insert line, delete line, insert
  81. spaces, delete spaces, etc.
  82.  
  83. Performance Results from ALL output sent:
  84.                            Raw      OptANSI       Other libraries   FNs
  85. WWIV BBS Capture (*):      69180    56241 - 19%   70683 + 2%        1
  86. PCBoard Capture (*):       41335    39374 - 5%    47763 + 15%       1
  87. Wildcat (*):               26639    19665 - 26%   27213 + 2%        1,2
  88. Doorway, Rmt DOS Capture:  51308    42610 - 17%   55389 + 8%        2,1
  89. TheDraw ANSI:              24271    23521 - 3%    28253 + 16%       2,1
  90.  
  91. Raw - Raw Output
  92. OptANSI - Raw Output retransmit through OptANSI
  93. Other Libraries - Raw Output retransmit through other libraries
  94. FNs - Primary ANSI functions were (in order of probability):
  95.         1 - Color Functions
  96.         2 - Location Functions
  97.         3 - Miscellaneous Functions
  98.  
  99. (*)  Results from BBS Systems are based on ANSI captures during a regular
  100. session with ANSI on. This includes newscanning files (FN 1), reading a
  101. message (FN1), writing a single reply with a full screen editor if available
  102. (FN 1,2), etc.
  103.  
  104. PCBoard's ANSI is pretty well optimized.
  105.  
  106. NOTE: The values above are probably not reflective of performance for your
  107. applications since many of the above programs have already been optimized,
  108. which goes to prove that it is probably a good idea.
  109.  
  110.  
  111. ------------------------------------------------------------------------------
  112. *REGISTERING OPTANSI*
  113.  
  114.      As a registered owner of the OptANSI library, you will get complete
  115. source code to the library. You can modify the source code to fit your needs
  116. if necessary, but you can never give out the OptANSI based source code even if
  117. it is modified beyond recognition. You also may not use the OptANSI library to
  118. make a competing library. Ergo, you cannot use OptANSI to make an optimizing
  119. ansi library that you distribute or sell to others, not even for other
  120. platforms [unless you get written permission from the author]. Also, there
  121. exists a copyright notice in the data of ainit. This does not need to be
  122. displayed anywhere in your programs, but must remain in the final executable.
  123. Do not remove this code from ainit.c. Other restrictions apply based on which
  124. license you pay. See below.
  125.  
  126.      No Royalties Apply to OptANSI library licenses. However, different
  127. licenses have different prices. Please read the information about each license
  128. option below to ensure that one you select is the one that satisfies your
  129. qualifications. Limitations apply to each. If you have questions or require
  130. special considerations, please contact the author listed below.
  131.  
  132.     -LICENSE OPTION------------------------------------ -REG PRICE-
  133.      Private license                                        $15
  134.      Shareware license                                      $30
  135.      Small commercial license                               $50
  136.      Full commercial license                                $500
  137.  
  138.      Printed documentation                              ADD $10
  139.      All Future Upgrades                                    $5
  140.  
  141. Private License: OptANSI library can only be included in software written
  142. which is NOT FOR SALE. Ie, it is part of your cost for doing business. One
  143. license applies to one person or one business dependi